<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!-- 
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

 http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License. 
-->
<html>
<head>
    <link type="text/css" rel="stylesheet" href="https://struts.apache.org/css/default.css">
    <style type="text/css">
        .dp-highlighter {
            width:95% !important;
        }
    </style>
    <style type="text/css">
        .footer {
            background-image:      url('https://cwiki.apache.org/confluence/images/border/border_bottom.gif');
            background-repeat:     repeat-x;
            background-position:   left top;
            padding-top:           4px;
            color:                 #666;
        }
    </style>
    <link href='https://struts.apache.org/highlighter/style/shCoreStruts.css' rel='stylesheet' type='text/css' />
    <link href='https://struts.apache.org/highlighter/style/shThemeStruts.css' rel='stylesheet' type='text/css' />
    <script src='https://struts.apache.org/highlighter/js/shCore.js' type='text/javascript'></script>
    <script src='https://struts.apache.org/highlighter/js/shBrushPlain.js' type='text/javascript'></script>
    <script src='https://struts.apache.org/highlighter/js/shBrushXml.js' type='text/javascript'></script>
    <script src='https://struts.apache.org/highlighter/js/shBrushJava.js' type='text/javascript'></script>
    <script src='https://struts.apache.org/highlighter/js/shBrushJScript.js' type='text/javascript'></script>
    <script src='https://struts.apache.org/highlighter/js/shBrushGroovy.js' type='text/javascript'></script>
    <script src='https://struts.apache.org/highlighter/js/shBrushBash.js' type='text/javascript'></script>
    <script type="text/javascript">
        SyntaxHighlighter.defaults['toolbar'] = false;
        SyntaxHighlighter.all();
    </script>
    <script type="text/javascript" language="javascript">
        var hide = null;
        var show = null;
        var children = null;

        function init() {
            /* Search form initialization */
            var form = document.forms['search'];
            if (form != null) {
                form.elements['domains'].value = location.hostname;
                form.elements['sitesearch'].value = location.hostname;
            }

            /* Children initialization */
            hide = document.getElementById('hide');
            show = document.getElementById('show');
            children = document.all != null ?
                    document.all['children'] :
                    document.getElementById('children');
            if (children != null) {
                children.style.display = 'none';
                show.style.display = 'inline';
                hide.style.display = 'none';
            }
        }

        function showChildren() {
            children.style.display = 'block';
            show.style.display = 'none';
            hide.style.display = 'inline';
        }

        function hideChildren() {
            children.style.display = 'none';
            show.style.display = 'inline';
            hide.style.display = 'none';
        }
    </script>
    <title>Wildcard Mappings</title>
</head>
<body onload="init()">
<table border="0" cellpadding="2" cellspacing="0" width="100%">
    <tr class="topBar">
        <td align="left" valign="middle" class="topBarDiv" align="left" nowrap>
            &nbsp;<a href="home.html">Home</a>&nbsp;&gt;&nbsp;<a href="guides.html">Guides</a>&nbsp;&gt;&nbsp;<a href="core-developers-guide.html">Core Developers Guide</a>&nbsp;&gt;&nbsp;<a href="configuration-elements.html">Configuration Elements</a>&nbsp;&gt;&nbsp;<a href="wildcard-mappings.html">Wildcard Mappings</a>
        </td>
        <td align="right" valign="middle" nowrap>
            <form name="search" action="https://www.google.com/search" method="get">
                <input type="hidden" name="ie" value="UTF-8" />
                <input type="hidden" name="oe" value="UTF-8" />
                <input type="hidden" name="domains" value="" />
                <input type="hidden" name="sitesearch" value="" />
                <input type="text" name="q" maxlength="255" value="" />
                <input type="submit" name="btnG" value="Google Search" />
            </form>
        </td>
    </tr>
</table>

<div id="PageContent">
    <div class="pageheader" style="padding: 6px 0px 0px 0px;">
        <!-- We'll enable this once we figure out how to access (and save) the logo resource -->
        <!--img src="/wiki/images/confluence_logo.gif" style="float: left; margin: 4px 4px 4px 10px;" border="0"-->
        <div style="margin: 0px 10px 0px 10px" class="smalltext">Apache Struts 2 Documentation</div>
        <div style="margin: 0px 10px 8px 10px"  class="pagetitle">Wildcard Mappings</div>

        <div class="greynavbar" align="right" style="padding: 2px 10px; margin: 0px;">
            <a href="https://cwiki.apache.org/confluence/pages/editpage.action?pageId=44247">
                <img src="https://cwiki.apache.org/confluence/images/icons/notep_16.gif"
                     height="16" width="16" border="0" align="absmiddle" title="Edit Page"></a>
            <a href="https://cwiki.apache.org/confluence/pages/editpage.action?pageId=44247">Edit Page</a>
            &nbsp;
            <a href="https://cwiki.apache.org/confluence/pages/listpages.action?key=WW">
                <img src="https://cwiki.apache.org/confluence/images/icons/browse_space.gif"
                     height="16" width="16" border="0" align="absmiddle" title="Browse Space"></a>
            <a href="https://cwiki.apache.org/confluence/pages/listpages.action?key=WW">Browse Space</a>
            &nbsp;
            <a href="https://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=WW&fromPageId=44247">
                <img src="https://cwiki.apache.org/confluence/images/icons/add_page_16.gif"
                     height="16" width="16" border="0" align="absmiddle" title="Add Page"></a>
            <a href="https://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=WW&fromPageId=44247">Add Page</a>
            &nbsp;
            <a href="https://cwiki.apache.org/confluence/pages/createblogpost.action?spaceKey=WW&fromPageId=44247">
                <img src="https://cwiki.apache.org/confluence/images/icons/add_blogentry_16.gif"
                     height="16" width="16" border="0" align="absmiddle" title="Add News"></a>
            <a href="https://cwiki.apache.org/confluence/pages/createblogpost.action?spaceKey=WW&fromPageId=44247">Add News</a>
        </div>
    </div>

    <div class="pagecontent">
        <div class="wiki-content">
            <div id="ConfluenceContent"><h2 id="WildcardMappings-Wildcards">Wildcards </h2>
<p>As an application grows in size, so will the number of action mappings. Wildcards can be used to combine similar mappings into one more generic mapping.</p>

<p>The best way to explain wildcards is to show an example and walk through how it works. This example modifies a conventional mapping to use wildcards to match all pages that start with /edit:</p>

<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">
&lt;action name="/edit*" class="org.apache.struts.webapp.example.Edit{1}Action"&gt;
    &lt;result name="failure"&gt;/mainMenu.jsp&lt;/result&gt;
    &lt;result&gt;{1}.jsp&lt;/result&gt;
&lt;/action&gt;
</pre>
</div></div>

<p>The "*" in the name attribute allows the mapping to match the request URIs /editSubscription, editRegistration, or any other URI that starts with /edit, however /editSubscription/add would not be matched. The part of the URI matched by the wildcard will then be substituted into various attributes of the action mapping and its action results replacing {1}. For the rest of the request, the framework will see the action mapping and its action results containing the new values.</p>

<p>Mappings are matched against the request in the order they appear in the framework's configuration file. If more than one pattern matches <strong>the last one wins</strong>, so less specific patterns must appear before more specific ones. However, if the request URL can be matched against a path without any wildcards in it, no wildcard matching is performed and order is not important. Also, note that wildcards are not greedy, meaning they only match until the first occurrence of the following string pattern.  For example, consider the following mapping:</p>

<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;">
&lt;action name="List*s" class="actions.List{1}s"&gt;
  &lt;result&gt;list{1}s.jsp&lt;/result&gt;
&lt;/action&gt;
</pre>
</div></div>

<p>This mapping would work correctly for the URI <code>ListAccounts</code> but not <code>ListSponsors</code>, because the latter would turn into this configuration:</p>

<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;">
&lt;action name="ListSpons" class="actions.ListSpons"&gt;
  &lt;result&gt;listSpons.jsp&lt;/result&gt;
&lt;/action&gt;
</pre>
</div></div>

<p>Wildcard patterns can contain one or more of the following special tokens:</p>
<div class="table-wrap"><table class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>*</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Matches zero or more characters excluding the slash ('/') character.</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>**</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Matches zero or more characters including the slash ('/') character.</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>\character</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>The backslash character is used as an escape sequence. Thus </p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>'\*'</pre>
</div></div>
<p> matches the character asterisk ('*'), and </p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>'\\'</pre>
</div></div>
<p> matches the character backslash ('\').</p></td></tr></tbody></table></div>


<div class="confluence-information-macro confluence-information-macro-note"><span class="aui-icon aui-icon-small aui-iconfont-warning confluence-information-macro-icon"></span><div class="confluence-information-macro-body">
<p>Patterns can optionally be matched "loosely". When the end of the pattern matches *[^*]*$ (wildcard, no wildcard, wildcard), if the pattern fails, it is also matched as if the last two characters didn't exist. The goal is to support the legacy "*!*" syntax, where the "!*" is optional.</p></div></div>

<p>In the action mapping and action results, the wildcard-matched values can be accessed with the token {N} where N is a number from 1 to 9 indicating which wildcard-matched value to substitute. The whole request URI can be accessed with the {0} token.</p>

<p>Also, the action mapping and action result properties will accept wildcard-matched strings in their value attribute, like:</p>
<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;">
&lt;action name="/edit/*" class="org.apache.struts.webapp.example.Edit{1}Action"&gt;
    &lt;param name="id"&gt;{1}&lt;/param&gt;
    &lt;result&gt;
      &lt;param name="location"&gt;/mainMenu.jsp&lt;/param&gt;
      &lt;param name="id"&gt;{1}&lt;/param&gt; 
    &lt;/result&gt;
&lt;/action&gt;
</pre>
</div></div>

<p><img class="emoticon emoticon-light-on" src="https://cwiki.apache.org/confluence/s/en_GB/5982/f2b47fb3d636c8bc9fd0b11c0ec6d0ae18646be7.1/_/images/icons/emoticons/lightbulb_on.png" data-emoticon-name="light-on" alt="(lightbulb)"> See also <a shape="rect" href="action-configuration.html">Wildcard Method</a></p>

<h2 id="WildcardMappings-Parametersinnamespaces">Parameters in namespaces</h2>
<p>From Struts 2.1+ namespace patterns can be extracted as request parameters and bound to the action. To enable this feature, set the following constant in struts.xml:</p>
<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;">
&lt;constant name="struts.patternMatcher" value="namedVariable"/&gt;
</pre>
</div></div>

<p>With that in place, namespace definitions can contain {PARAM_NAME} patterns which will be evaluated against the request URL and extracted as parameters, for example:</p>
<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">
@Namespace{"/users/{userID}");
public class DetailsAction exends ActionSupport {
  private Long userID;
  public void setUserID(Long userID) {...}
}
</pre>
</div></div>
<p>If the request URL is <em>/users/10/detail</em>, then the DetailsAction will be executed and its userID field will be set to <em>10</em>. </p>

<div class="confluence-information-macro confluence-information-macro-warning"><span class="aui-icon aui-icon-small aui-iconfont-error confluence-information-macro-icon"></span><div class="confluence-information-macro-body">
<p>Only one PatternMatcher implementation can be used at a time.  The two implementations included with Struts 2 are mutually exclusive.  You cannot use Wildcards and Named Variable patterns at the same application (if that were required, you'd need to create a custom PatternMatcher implementation).</p>

<p>Some tags tags not are 100% compatible with variables in the namespace. For instance, they may write the literal namespace into the HTML (eg /{user}/2w) instead of the path used in the request (ie. /brett/24).  This usually affects attributes that attempt to guess the namespace of an action (eg. Form tag, Action tag, action=). This problem can be avoided by using HTML tags directly with relative paths or explicit URLs.</p></div></div>

<div class="confluence-information-macro confluence-information-macro-note"><span class="aui-icon aui-icon-small aui-iconfont-warning confluence-information-macro-icon"></span><div class="confluence-information-macro-body">
<p>Similar functionality can also be implemented using a custom ActionMapper.  The ActionMapper will need to parse the namespace and request itself to set parameters on the matched action.  The default ActonMapper is responsible for invoking the PatternMatcher.</p></div></div>

<h2 id="WildcardMappings-Parametersaftertheactionname">Parameters after the action name</h2>
<p>To use parameters in the URL, after the action name, make sure this is set:</p>
<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;">
&lt;constant name="struts.enable.SlashesInActionNames" value="true"/&gt;
&lt;constant name="struts.mapper.alwaysSelectFullNamespace" value="false"/&gt;
</pre>
</div></div>
<p>Then the action mapping will look like:</p>
<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;">
&lt;package name="edit" extends="struts-default" namespace="/edit"&gt;
    &lt;action name="/person/*" class="org.apache.struts.webapp.example.EditAction"&gt;
        &lt;param name="id"&gt;{1}&lt;/param&gt;
        &lt;result&gt;/mainMenu.jsp&lt;/result&gt;
    &lt;/action&gt;   
&lt;/package&gt;
</pre>
</div></div>
<p>When a URL like <code>/edit/person/123</code> is requested, EditAction will be called, and its "id" field will be set to 123. </p>

<h2 id="WildcardMappings-AdvancedWildcards">Advanced Wildcards</h2>
<p>From 2.1.9+ regular expressions can be defined defined in the action name. To use this form of wild card, the following constants must be set:</p>
<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;">
&lt;constant name="struts.enable.SlashesInActionNames" value="true"/&gt;
&lt;constant name="struts.mapper.alwaysSelectFullNamespace" value="false"/&gt;
&lt;constant name="struts.patternMatcher" value="regex" /&gt;
</pre>
</div></div>

<p>The regular expressions can be in two forms, the simplest one is {FIELD_NAME}, in which case the field with the FIELD_NAME in the action will be populated with the matched text, for example:</p>

<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;">
&lt;package name="books" extends="struts-default" namespace="/"&gt;
    &lt;action name="/{type}/content/{title}" class="example.BookAction"&gt;
	&lt;result&gt;/books/content.jsp&lt;/result&gt;
    &lt;/action&gt;
&lt;/package&gt;
</pre>
</div></div>
<p>In this example, if the url <code>/fiction/content/Frankenstein</code> is requested, BookAction's field "type" will be set to "fiction", and the field "title" will be set to "Frankenstein". </p>

<p>The regular expression can also be in the form {FIELD_NAME:REGULAR_EXPRESSION}. The regular expression is a normal Java regular expression. For example:</p>

<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;">
&lt;package name="books" extends="struts-default" namespace="/"&gt;
    &lt;action name="/{type}/{author:.+}/list" class="example.ListBooksAction"&gt;
	&lt;result&gt;/books/list.jsp&lt;/result&gt;
    &lt;/action&gt;
&lt;/package&gt;
</pre>
</div></div>
<p>In this example, if the url <code>/philosophy/AynRand/list</code> is requested, ListBooksAction's field "type" will be set to "philosophy" and "author" to "AynRand". </p>

<p>The matched groups can still be accessed using the {X} notation, like:</p>
<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;">
&lt;package name="books" extends="struts-default" namespace="/"&gt;
    &lt;action name="/books/{ISBN}/content" class="example.BookAction"&gt;
	&lt;result&gt;/books/{1}.jsp&lt;/result&gt;
    &lt;/action&gt;
&lt;/package&gt;
</pre>
</div></div>

<h2 id="WildcardMappings-Next:">Next: <a shape="rect" href="application-servers.html">Application Servers</a></h2></div>
        </div>

        
    </div>
</div>
<div class="footer">
    Generated by CXF SiteExporter
</div>
</body>
</html>
